Flexible declaration styling #9023

jakobandersen · 2021-03-20T16:17:18Z

Feature or Bugfix

Feature
Refactoring

Purpose

Attempt to resolve a foundational chunk of #4289, building on #7145, #6990, #4390.

Examples of difference in HTML rendering

Current: https://jakobandersen.github.io/ex_sphinx_decl_styling/master/
With this: https://jakobandersen.github.io/ex_sphinx_decl_styling/with_9023/

For seeing the differences for the Python domain (change to monospace font) see e.g., extdev/appapi.html.
For the difference in styling with colouring in the C++ domain see e.g., usage/restructuredtext/domains.html#_CPPv46MyList.

Additional example of C++ differences

Current:

With this PR:

Details

Add more nodes derived from addnodes.desc_sig_element,
and document them as being the leaf-nodes of signatures.
That is, they only contain text, no other nodes.
Document the nodes desc, desc_signature, desc_signature_line, and desc_content
as the nodes that form the top levels of object descriptions.
Document the remaining desc_nodes as being high-level structuring nodes for signatures.
Document which classes are always in the desc_ nodes.
Revamp the C++ domain to use the new nodes, and never nodes.Text nodes.
Restructure the CSS in the basic theme to group by this node classification.
Move classes on nodes to addnodes from the HTML and HTML5 writers.
Introduce a new top-level desc_inline node for signature fragments in text.
This is not for xrefs, but for roles like cpp:expr which contain arbitrary expressions or types.
Add new classes on the two top-level signature-containing nodes desc_signature and desc_inline.
Both get sig the domain name, and in addition sig-object and sig-inline respectively.
While desc contains the domain, this also has arbitrary descriptions as decendants,
so you can have a py:function with a description that contains a cpp:expr.
If you want to style, e.g., keywords differently in the two languages, you can now select
.sig.py .k and .sig.cpp .k without them overlapping.
HTML: Change desc_name and desc_addname from using a code tag to a span,
and instead make all .sig use monospace as font-family consistently.
Add styling to C++ signatures based on the IntellliJ theme.

Next steps, perhaps for future PRs

~~Only the basic theme has been changed. The rest should be checked.~~ (done)
@jfbu, the Latex implementation of desc_inline is quick copy paste. The compiled PDF looks fine to me, but please check, e.g., with something like :cpp:expr:`a + b`
There are some more desc_ nodes perhaps should be looked at:
desc_type, desc_returns, desc_parameterlist, desc_parameter, desc_optional, and desc_annotation.
I suggest doing this in a separate PR.
As discussed in Flexible styling of declarations #4289 it may be nice to also have flexible styling in Latex. As the current classes are way fewer than in Pygments I don't think a direct link to their styles is relevant. I suggest doing this in a separate PR if those using the Latex output would like it, but it would be nice to get feedback already now if there is a problem with the design suggested here (ping @jfbu ?).
~~Convert the C domain to use the new nodes.~~ (done)
Convert other domains to use the new nodes?

jakobandersen · 2021-03-25T20:00:00Z

I think it is now in a potentially mergeable state, ready to review.

sphinx/addnodes.py

sphinx/transforms/post_transforms/__init__.py

sphinx/writers/manpage.py

sphinx/addnodes.py

tk0miya · 2021-04-04T08:58:44Z

LGTM with nits!

jakobandersen · 2021-04-07T18:52:06Z

LGTM with nits!

Thanks! It should be ready for a second round now.

As a general point: what is your opinion on how to use SigElementFallbackTransform? If we should minimize the use of it, I suggest we add warnings whenever it triggers so builders can become aware of missing implementations.

tk0miya · 2021-04-11T16:17:58Z

As a general point: what is your opinion on how to use SigElementFallbackTransform? If we should minimize the use of it, I suggest we add warnings whenever it triggers so builders can become aware of missing implementations.

Ideally, all writers should support all of the new nodes. But it increases the maintenance cost of the 3rd party builders. So I'm afraid that the warnings kill their deprecation because of the lack of maintenance. So -0 for emitting warnings.

jakobandersen · 2021-04-11T16:22:52Z

So I'm afraid that the warnings kill their deprecation because of the lack of maintenance.

Good point, as noted in the review comment, I'll ensure that at least the writers bundled with Sphinx only needs the fallback for the desc_sig_element nodes. After that I'll merge into 4.0.0, ok?

tk0miya · 2021-04-11T16:24:11Z

Yes. I'll review this again tomorrow (or the next day). After that, let's merge this into 4.0.x branch.

tk0miya · 2021-04-12T16:56:54Z

LGTM again. +1 for merging if fallback-transform supports the desc_inline node.

jakobandersen · 2021-04-12T17:03:10Z

Thanks for the reviews! I'll rebase to 4.0.x and merge.

Use the new node for cpp:expr

…_signature nodes

Add test objects so all builders gets exposed to the new nodes. Make the fallback node post-transform change desc_inline as well. Make the html4, latex, and text writers handle desc_inline.

jakobandersen force-pushed the decl_styling branch from 2aa6d5f to 7bb2473 Compare March 20, 2021 16:22

jakobandersen added domain domains:cpp type:enhancement enhance or introduce a new feature labels Mar 20, 2021

jakobandersen force-pushed the decl_styling branch 2 times, most recently from 4bfefc5 to b16cb6c Compare March 25, 2021 19:50

jakobandersen requested review from tk0miya and jfbu March 25, 2021 19:58

jakobandersen changed the title ~~[WIP] Flexible declaration styling~~ Flexible declaration styling Mar 25, 2021

This was referenced Mar 26, 2021

Add various specifiers to functions and variables breathe-doc/breathe#628

Merged

Data/return type concatenated to variables/function name breathe-doc/breathe#655

Closed

jakobandersen added this to the 4.0.0 milestone Mar 29, 2021

jakobandersen added the domains:c label Mar 30, 2021

jakobandersen force-pushed the decl_styling branch from 6fd299d to ed700ea Compare March 30, 2021 14:33

tk0miya reviewed Apr 4, 2021

View reviewed changes

jakobandersen mentioned this pull request Apr 7, 2021

4.0.0 release plan #9056

Closed

jakobandersen requested a review from tk0miya April 7, 2021 18:52

tk0miya modified the milestones: 4.0.0, 4.1.0 Apr 11, 2021

jakobandersen added 3 commits April 12, 2021 19:05

Decl styling, more nodes and C++ conversion

14f7d24

Decl styling, docs and restructuring

3c9a74c

Decl styling, move desc dynamic classes to domain base class

d131ec7

jakobandersen added 17 commits April 12, 2021 19:05

Decl styling, move static classes to addnodes from HTML5 writer

e012c93

Decl styling, make desc_inline node

98800be

Use the new node for cpp:expr

Decl styling, consistent monospace

b0a2e5c

Fix flake8 and mypy violations

86eeee5

Decl styling, use a post-transform to get the domain name in the desc…

c1da955

…_signature nodes

Decl styling, add CSS for the C++ domain

70708e4

Decl styling, fix cpp tests

87414fa

Fix desc_sig_space

3fdc9bc

Decl styling, fix html test

f769dde

Fix isort violation

c0ef6a9

Decl styling, update writers

7126503

Add test objects so all builders gets exposed to the new nodes. Make the fallback node post-transform change desc_inline as well. Make the html4, latex, and text writers handle desc_inline.

Decl styling, C++, fix alternate spellings of operators

a1ac0fd

Decl styling, convert C

9cd9e12

Decl styling, C styling and C++ char literal styling

f1d9d0a

C, C++, fix unary op

a840b9e

Decl styling, fixes from review

da5b8e4

Decl styling, handle desc_inline in manpage and texinfo

cb21eb2

jakobandersen force-pushed the decl_styling branch from 08ad74a to cb21eb2 Compare April 12, 2021 17:08

jakobandersen changed the base branch from master to 4.0.x April 12, 2021 17:08

jakobandersen added 2 commits April 12, 2021 20:24

Decl styling, fix font size in basic

9b3b8a4

Decl styling, disable smart quoting in sigs

709339e

jakobandersen merged commit 8954770 into sphinx-doc:4.0.x Apr 12, 2021

jakobandersen deleted the decl_styling branch April 12, 2021 20:05

jakobandersen mentioned this pull request Apr 12, 2021

Some themes do not import CSS from basic #9093

Open

jakobandersen mentioned this pull request May 18, 2021

Parsing issues with Sphinx 4.0.1 breathe-doc/breathe#700

Closed

jakobandersen mentioned this pull request Jun 29, 2021

Missing spaces inside dt's readthedocs/sphinx_rtd_theme#694

Closed

github-actions bot locked as resolved and limited conversation to collaborators Jul 12, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Flexible declaration styling #9023

Flexible declaration styling #9023

jakobandersen commented Mar 20, 2021 •

edited

Loading

jakobandersen commented Mar 25, 2021

tk0miya commented Apr 4, 2021

jakobandersen commented Apr 7, 2021

tk0miya commented Apr 11, 2021

jakobandersen commented Apr 11, 2021

tk0miya commented Apr 11, 2021

tk0miya commented Apr 12, 2021

jakobandersen commented Apr 12, 2021

Flexible declaration styling #9023

Flexible declaration styling #9023

Conversation

jakobandersen commented Mar 20, 2021 • edited Loading

Feature or Bugfix

Purpose

Examples of difference in HTML rendering

Additional example of C++ differences

Details

Next steps, perhaps for future PRs

jakobandersen commented Mar 25, 2021

tk0miya commented Apr 4, 2021

jakobandersen commented Apr 7, 2021

tk0miya commented Apr 11, 2021

jakobandersen commented Apr 11, 2021

tk0miya commented Apr 11, 2021

tk0miya commented Apr 12, 2021

jakobandersen commented Apr 12, 2021

jakobandersen commented Mar 20, 2021 •

edited

Loading